home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / RCS / Swap.man,v < prev    next >
Text File  |  1989-11-27  |  6KB  |  175 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     89.11.27.17.34.25;  author douglis;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     88.12.30.14.34.35;  author ouster;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @added notation that this is obsolete
  27. @
  28. text
  29. @' $Header: /sprite/src/lib/c/etc/RCS/Swap.man,v 1.1 88/12/30 14:34:35 ouster Exp Locker: douglis $ SPRITE (Berkeley)
  30. .so \*(]ltmac.sprite
  31. .HS Swap lib
  32. .BS
  33. .SH NAME
  34. Swap_Buffer \- Do byte-swapping and alignment of data buffers
  35. .br
  36. Swap_BufSize \- Calculate the necessary buffer size to hold swapped and aligned data
  37. .SH SYNOPSIS
  38. \fB#include <swapBuffer.h>\fR
  39. .sp
  40. void
  41. \fBSwap_Buffer\fR(\fIinBuf, inSize, inType, outType, format, outBuf, outSizePtr\fR)
  42. .sp
  43. void
  44. \fBSwap_BufSize\fR(\fIinBuf, inSize, inType, outType, format, outSizePtr\fR)
  45. .SH ARGUMENTS
  46. .AS Option *optionArray
  47. .AP char *inBuf in
  48. In-coming data buffer
  49. .AP int inSize in
  50. Size in bytes of inBuf
  51. .AP int inType in
  52. Type of byte-order and alignment of data in inBuf
  53. .AP int outType in
  54. Type of byte-order and alignment of data in outBuf
  55. .AP char *format in
  56. String describing format of data in inBuf (see below for more details)
  57. .AP char *outBuf out
  58. Buffer in which to put out-going swapped and aligned data
  59. .AP int *outSizePtr in/out
  60. outSizePtr is an in/out parameter for \fBSwap_Buffer()\fR, but just an out
  61. parameter for \fBSwap_BufSize()\fR.  See below for its use in \fBSwap_Buffer()\fR and
  62. \fBSwap_BufSize()\fR.
  63. .BE
  64. .SH DESCRIPTION
  65. .PP
  66. These routines are obsolete.  See \fbFmt\fR instead.
  67. .PP
  68. \fBSwap_Buffer()\fR takes a buffer of data (\fIinBuf\fR) from one machine byte-order
  69. and alignment type (\fIinType\fR) and produces an output buffer (\fIoutBuf\fR)
  70. of the same data swapped and aligned
  71. to conform to a different machine byte-order and alignment type (\fIoutType\fR).
  72. The parameter \fIoutSizePtr\fR is an in/out parameter to \fBSwap_Buffer()\fR.
  73. In a call to \fBSwap_Buffer()\fR, \fI*outSizePtr\fR should contain the size in bytes
  74. of the buffer parameter \fIoutBuf\fR.  As \fBSwap_Buffer()\fR
  75. returns, \fI*outSizePtr\fR
  76. contains the actual size of the swapped and aligned data.  If the return value
  77. of \fI*outSizePtr\fR is larger than its input value, then \fBSwap_Buffer()\fR needed
  78. more buffer space for the out-going data than \fIoutBuf\fR provided.  In this
  79. case, \fBSwap_Buffer()\fR stops swapping the data and instead calculates the amount
  80. of space in bytes that it needs.   It returns that value in \fI*outSizePtr\fR.
  81. If \fI*outSizePtr\fR returns with a 0 value, then an error occurred, such
  82. as the \fIformat\fR argument contained unrecognizable characters or contained
  83. a '*' character in a position other than the last character (see description
  84. of format string, below), or the sizes of the \fIformat\fR string or \fIinBuf\fR
  85. weren't compatible.  In the case of an error,
  86. if \fBSwap_Buffer()\fR is called from a user process, it will
  87. panic with an error string explaining the problem.  If called in the kernel,
  88. it will print a warning-level system error message and return.
  89. .PP
  90. \fBSwap_BufSize()\fR calculates the size required for the \fIoutBuf\fR parameter
  91. to \fBSwap_Buffer()\fR given the same input data (\fIinBuf\fR), byte-ordering
  92. types (\fIinType\fR and \fIoutType\fR), and the same data
  93. format (\fIformat\fR).  It returns this calculated value in \fI*outSizePtr\fR.
  94. If *outSizePtr returns with a zero, then an error occurred.  (See the errors
  95. listed above for \fBSwap_Buffer()\fR for details.)
  96. Different machines have different alignment (and thus padding) requirements,
  97. and this is why the size of the out-going data may be different from the
  98. size of the in-coming data.
  99. .PP
  100. The format
  101. string (\fIformat\fR) must describe the configuration of the data in
  102. the input buffer, \fIinBuf\fR.  The
  103. data can contain bytes, half-words (4 bytes), words (8 bytes) and double-words
  104. (16 bytes).
  105. .PP
  106. The format string describes these data
  107. types as follows:
  108. .IP "'b'"
  109. The character 'b' stands for a byte value (1 byte).
  110. .IP "'h'"
  111. The character 'h' stands for a half-word (2 bytes).
  112. .IP "'w'"
  113. The character 'w' stands for a word (4 bytes).
  114. .IP "'d'"
  115. The character 'd' stands for a double-word (8 bytes and not yet implemented).
  116. .IP "'0'-'9'*"
  117. A number in ascii means that the previous value type ('b, 'h', 'w', or 'd')
  118. is repeated the given number
  119. of times.  For instance, the string "w88" means that inBuf contains
  120. 88 word values in a row.
  121. .IP "\'*'"
  122. A '*' character means 1 or more occurrences of the previous value type.
  123. A '*' can only appear at the end of a format string, since otherwise there's no
  124. way to determine the actual number of repetitions of the previous value.
  125. .PP
  126. An example format string, "bwwh3w5b*", would describe a buffer
  127. containing the structure
  128. .DS
  129. .ta 1c 2c 3c 4c 5c 6c
  130.     struct    flea    {
  131.         char    mite;
  132.         int        spider;
  133.         int        worm;
  134.         short    moth;
  135.         short    mosquito;
  136.         short    beetle;
  137.         int        fly[5];
  138.         char    gnat[50];
  139.     };
  140. .DE
  141. .LP
  142. The machine byte-order and alignment types are defined in swapBuffer.h.
  143. Their names may change since complaints have been registered about the
  144. current names, but currently the types are as follows:
  145. .IP "\fBSWAP_SUN_TYPE\fR"
  146. The byte-ordering and alignment of 68020's.  Looking at an integer as if
  147. it were an array of 4 bytes (char buf[4]), buf[0] contains the low byte,
  148. buf[3] contains the high byte, and half-words and words are aligned
  149. to half-word boundaries.
  150. .IP "\fBSWAP_VAX_TYPE\fR"
  151. The byte-ordering and alignment of Vaxen.  Looking at an integer as if
  152. it were an array of 4 bytes (char buf[4]), buf[0] contains the high byte,
  153. buf[3] contains the low byte, and half-words and words are aligned
  154. to half-word boundaries.
  155. .IP "\fBSWAP_SPUR_TYPE\fR"
  156. The byte-ordering and alignment of the Spur machine.  Looking at an integer
  157. as if it were an array of 4 bytes (char buf[4]), buf[0] contains the high byte,
  158. buf[3] contains the low byte.  Half-words are half-word aligned and
  159. words are word aligned.
  160. .SH KEYWORDS
  161. byte-order, byte-swap, padding, alignment
  162. @
  163.  
  164.  
  165. 1.1
  166. log
  167. @Initial revision
  168. @
  169. text
  170. @d1 1
  171. a1 1
  172. ' $Header: Swap_Buffer,v 1.2 88/09/14 16:53:42 mlgray Exp $ SPRITE (Berkeley)
  173. d37 2
  174. @
  175.